home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / tcl / tcl67.lha / tcl6.7 / doc / AssembCmd.3 < prev    next >
Text File  |  1993-01-31  |  3KB  |  88 lines
  1. '\"
  2. '\" Copyright 1989-1992 Regents of the University of California
  3. '\" Permission to use, copy, modify, and distribute this
  4. '\" documentation for any purpose and without fee is hereby
  5. '\" granted, provided that this notice appears in all copies.
  6. '\" The University of California makes no representations about
  7. '\" the suitability of this material for any purpose.  It is
  8. '\" provided "as is" without express or implied warranty.
  9. '\" 
  10. '\" $Header: /user6/ouster/tcl/man/RCS/AssembCmd.3,v 1.4 93/01/31 15:35:27 ouster Exp $ SPRITE (Berkeley)
  11. '\" 
  12. .so man.macros
  13. .HS Tcl_AssembleCmd tcl
  14. .BS
  15. .SH NAME
  16. Tcl_CreateCmdBuf, Tcl_AssembleCmd, Tcl_DeleteCmdBuf \- buffer pieces of Tcl commands
  17. .SH SYNOPSIS
  18. .nf
  19. \fB#include <tcl.h>\fR
  20. .sp
  21. Tcl_CmdBuf
  22. \fBTcl_CreateCmdBuf\fR()
  23. .sp
  24. \fBTcl_DeleteCmdBuf\fR(\fIbuffer\fR)
  25. .sp
  26. char *
  27. .VS
  28. \fBTcl_AssembleCmd\fR(\fIbuffer\fR, \fIstring\fR)
  29. .VE
  30. .sp
  31. int
  32. \fBTcl_CommandComplete\fR(\fIcmd\fR)
  33. .SH ARGUMENTS
  34. .AS Tcl_CmdBuf *string;
  35. .AP Tcl_CmdBuf buffer in
  36. Token for a command buffer (the result of some previous call to
  37. \fBTcl_CreateCmdBuf\fR).
  38. .AP char *string in
  39. Additional piece of command input to be added to anything currently
  40. buffered.
  41. .AP char *cmd in
  42. .VS
  43. Command string to test for completeness.
  44. .VE
  45. .BE
  46.  
  47. .SH DESCRIPTION
  48. .PP
  49. These procedures provide a convenient mechanism for assembling
  50. Tcl commands from an input source where command boundaries are not
  51. obvious.  For example, if input is being read from a terminal, a user
  52. may type commands that span multiple lines.  In situations like
  53. this, \fBTcl_AssembleCmd\fR can be called with the individual lines
  54. as they are received.  It buffers the lines internally and returns
  55. full commands when they are complete.
  56. .PP
  57. A command buffer is created by calling \fBTcl_CreateCmdBuf\fR, and
  58. it is deleted by calling \fBTcl_DeleteCmdBuf\fR.  There may be any
  59. number of command buffers for a particular program or even for a
  60. particular interpreter;  in most cases there should be one
  61. buffer for each independent source of command input.
  62. .PP
  63. When input arrives from a source you should call \fBTcl_AssembleCmd\fR,
  64. passing it the new input as the \fIstring\fR argument.
  65. \fBTcl_AssembleCmd\fR will add the new input to anything currently
  66. buffered in \fIbuffer\fR.  If the information now buffered represents
  67. a complete Tcl command (i.e. there are no unclosed quotes, braces,
  68. brackets, or variable references),
  69. then \fBTcl_AssembleCmd\fR returns a pointer to the complete command
  70. and arranges for the buffer to be cleared on the next call to
  71. \fBTcl_AssembleCmd\fR.  If the command is still incomplete (because,
  72. for example, there are unmatched braces) then \fBTcl_AssembleCmd\fR
  73. returns NULL.  \fBTcl_AssembleCmd\fR keeps a private copy of the
  74. command being assembled, so that the caller need not preserve the
  75. contents of \fIstring\fR between calls to \fBTcl_AssembleCmd\fR.
  76. \fBTcl_AssembleCmd\fR supports commands of arbitrary length (up to
  77. the total memory limit imposed by the operating system, if any).
  78. .PP
  79. .VS
  80. The procedure \fBTcl_CommandComplete\fR takes a Tcl command string
  81. as argument and determines whether the command string is complete
  82. in the sense defined above.
  83. If so then it returns 1; otherwise it returns 0.
  84. .VE
  85.  
  86. .SH KEYWORDS
  87. assemble, buffer, partial command
  88.